!lm12
!rm75
Using the Applied Engineering Time II......Bob Sander-Cederlof

You have probably noticed Dan Pote's ad in this and previous issues of AAL.  I finally got one of his clock-calendar cards, and learned how to program it.

A disk full of sample programs comes with the board, but none of them were exactly what I wanted.  I wanted a simple short program to read the time and date and display it on the screen; and I wanted some patches to DOS 3.3 which would append the date in MM/DD/YY format to any files SAVEd or BSAVEd.

The clock already had the correct time and date set when it arrived in the mail.  The onboard rechargeable battery keeps the circuit running even when you remove the card from your computer!  A couple of times I stopped the clock when I was working on my programs, so I just used one of the time-setting programs on the disk to correct the time.

How do you read the time and date?  There are 13 registers on the board.  Each register holds one digit of the time and date information.  To read a particular register, you store the register number into the clock input port, and then read the clock output port.

In order to avoid reading the time or date while it is being changed, you momentarily stop the clock before reading, and restart it when you are finished.  You don't want to keep the clock stopped for more than one second, or it will lose time.  After stopping the clock, you have to wait at least 150 microseconds before reading it.  If the clock was updating when you stopped it, the delay allows the update in progress to complete.

The following program reads the time and date and writes it on the bottom line of the screen.

<program here>

My Time II card is in slot 5.  It will work in any slot from 1 to 7.  Change line 1040 if you use a different slot.  There are two addresses used to talk to the Time II card:  $C081+slot*16, and $C082+slot*16.  For slot 5, these are $C0D1 and $C0D2.  Line 1070 loads "slot*16" into the X-register, so that loads and stores into the Time II registers will be directed to the proper slot.

Lines 1080,1090 stop the clock.  Storing any value at $C0D1 of the form xxx1xxxx will stop the clock.  If bit 4 is a zero the clock will be started again, as in lines 1270,1280.

Lines 1100-1260 read the date and time and store them on the screen.  The reading is under the control of a format map, line 1340.  The format map contains three kinds of bytes:  00, meaning the end of the map; 2x, register addresses; and ASCII characters with the high bit set.  The Y-register indexes access to the map, and also the corresponding position on the screen line.

Lines 1110-1130 get the next map byte, and analyze it.  If it is 00, the time and date have been read; then lines 1270-1320 restart the clock and test if you want to keep reading or not.  If the byte is negative, then it is an ASCII character; Line 1240 stores the character on the screen line, and reading continues.  If neither zero nor negative, the byte is a register address.  Line 1140 selects the register by storing its address at $C0D2.

Lines 1150-1230 read the selected register.  If the register was the tens-digit of the hour, then the flag bits are removed.  These flag bits indicate whether you are using 12-hour or 24-hour format in the Time II, and AM/PM status.  I didn't care, so I just mask them out.  I also replaced a leading zero digit with blank here.  Line 1230 converts the digit to an ASCII character.

Lines 1290-1320 test whether you have pressed any key on the keyboard.  If not, reading continues.  If you did, the storbe is cleared and the program terminates after printing a carriage return.

Here is a summary of the clock register addresses:
!lm17

             tens units
Seconds       21   20
Minutes       23   22
Hours         25   24   with 12/24 and AM/PM flags
Day of Week        26
Day of Month  28   27
Month         2A   29
Year          2C   2B

!lm12
The second program I wrote only reads the date.  The actual reading is very similar to the first program, but the purpose is different.  Instead of displaying it on the screen, I store in in the last 8 positions of the primary file name buffer inside DOS 3.3.  The patches in lines 1040-1140 set up SAVE and BSAVE to call my program before opening the file.  My program then modifies the file name to include the current date as the last 8 characters.

I located the program inside a hole in DOS 3.3 ($B6B3-$B6FD).  If you are already using a modified DOS, this hole may already have some code in it, so be careful.  For example, the DOS on Applied Engineering's disk IS modified, and the modification uses this same space.

When you assemble this program, the four .TF directives write four short little binary files (B.1, B.2, B.3, and B.4).  I wrote a four line EXEC file to BLOAD these four binary files, installing the patches.

<program here>

The program saves the contents of the A-register at line 1220, and restores A at line 1390.  Lines 1230,1240 stop the clock so we can read it.  Lines 1250-1270 delay for about 150 microseconds in case the clock was updating when I stopped it.

Lines 1280-1360 read the date under control of a format map in line 1420, almost the same way the first program did.  This time I used the known length of 8 bytes to terminate the loop, rather than a final 00 byte.  Line 1340 stores inside the DOS primary file name buffer ($AA75-$AA92).

Lines 1370-1380 turn the clock back on.  Line 1390 restores the A-register, and line 1400 continues with the normal DOS 3.3 code.

Before arriving at the above technique, I tried several others.  I had one working which patched the DOS File Manager instead of the SAVE and BSAVE commands.  This version appended the date to the name of any and all new files created.  It worked exactly as it should, but it would have caused many problems with existing programs.  Many Applesoft and Integer BASIC programs using TEXT files use an OPEN-DELETE-OPEN-WRITE sequence to make sure that a new file is used for output.  If my patch to the file manager was installed, this sequence would not work correctly anymore.  Therefore I elected to go the more direct route, only dating SAVE and BSAVE files.

If you want to use the date on TEXT file names, you could append it to the file name using normal string concatenation techniques.

I have not used any other of the clock/calendar cards available for the Apple, but I am convinced the Time II from Applied Engineering is a good one.  (It may also be the least expensive.)  The circuit card is professionally done; the components are highest quality; it works when you plug it in.  There are other features, such as interrupt capability, which I have not yet explored.  If you have any use for a clock/calendar, I recommend this one.
